Repository navigation
docs: clarify Replica onboarding paths - #100
Conversation
Separate local prototyping, shared hosting, and joining an existing team. Clarify prerequisites and continuation steps, and update the README with product framing and a demo. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 045ed8e1-41ea-44f3-a2c6-d9f485f87ca1
There was a problem hiding this comment.
🟡 Changes recommended
Documented onboarding paths can still leave users blocked before setup or first publication completes.
3 open issues
What changed in this PR
Clarifies Replica onboarding by separating local prototyping, shared hosting, and joining an existing team environment.
Changes:
- Adds a local walkthrough covering repository setup, canvas activation, team guidance, and a first prototype.
- Expands hosted setup with early infrastructure checks and continuation points that reuse completed work.
- Updates README framing, demo content, and navigation while keeping repository setup instructions focused on Copilot.
| File | Description |
|---|---|
README.md |
Updates product framing, demo content, and the three onboarding paths. |
hub/docs/deployment.md |
Adds outbound network requirements for deployment and Hub. |
docs/README.md |
Distinguishes user walkthroughs from the supporting agent guide. |
docs/prototype-repository-setup.md |
Clarifies Copilot’s repository setup, approvals, and session handoff. |
docs/prototype-environment.md |
Expands shared hosting setup from readiness checks through team feedback. |
docs/local-prototyping.md |
Adds the local-first prototyping walkthrough and sharing continuations. |
docs/getting-started.md |
Focuses onboarding on joining an existing team environment. |
Review effort: Max
Added instructions for checking workflow presence and handling merges. Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Updated the running Hub container section to include GitHub sign-in requirements and clarified the connection process for the GitHub App. Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Resolve conflict in hub/docs/deployment.md by keeping both the new outbound network access section and the new server-side tracing section. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 424c906c-5e6b-4d71-ba71-edd25c7c1191
Reformatted instructions for clarity and readability.
yaili
left a comment
yaili
left a comment
There was a problem hiding this comment.
Thank you, @cmcnally.
Generally it feels easier to follow, but I think we need a review focused on the following:
- Introduce formatting that makes sense for the text (e.g. I made a direct edit in the first section where it made sense to have list items)
- Separate more clearly what is a step and what is commentary.
- Break up long paragraphs that should be lists or some other format.
Use ordered steps for actions, lists for requirements, and tables for setup alternatives. Separate explanations and recovery help while preserving reviewer edits, existing headings, commands, and prompts. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 045ed8e1-41ea-44f3-a2c6-d9f485f87ca1
|
Thank you for your helpful feedback @yaili , I have adjusted and applied all of your feedback across these docs. |
Preserve the clearer onboarding flow while incorporating main's starter choices, initial-commit behavior, and shared guide paths. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 045ed8e1-41ea-44f3-a2c6-d9f485f87ca1
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 045ed8e1-41ea-44f3-a2c6-d9f485f87ca1
| ## Get started with Replica | ||
|
|
||
| Replica has four parts: | ||
| You don't need to set up everything at once. Start with the guide that matches your next step: trying Replica locally, setting up hosting, or joining your team's existing repository and Hub. | ||
|
|
||
| | Part | What it does | | ||
| | Your goal | Start here | | ||
| | --- | --- | | ||
| | **Starters** | Create a local prototype project from your choice of app, with shared agent skills. | | ||
| | **Copilot canvas extension** | Opens your local prototype alongside your Copilot conversation. | | ||
| | **Replica Hub (optional)** | Hosts published prototypes so your team can try them and leave comments. | | ||
| | **GitHub build action** | Builds prototypes for publishing to Hub. It is not needed for local prototyping. | | ||
| | Start or continue prototyping locally | [Create your first local prototype](docs/local-prototyping.md). Use the starter or an existing prototype repository, add team guidance, and build something useful. No Hub required. | | ||
| | Set up hosting and comments for your team | [Set up shared hosting and team feedback](docs/prototype-environment.md). Check hosting needs early, build with your team's design guidance, and connect Hub when it is ready. | | ||
| | Join a team with a repository and Hub already in use | [Join your team's Replica environment](docs/getting-started.md). Use its existing setup to create, publish, and review a prototype. | | ||
|
|
||
| **Ready to make prototypes?** Follow [Get started with Replica](docs/getting-started.md) to install the GitHub Copilot app, add your team's prototyping repository, install the canvas, and create your first prototype. It also covers connecting to Hub, publishing, sharing and commenting, and adding controls. | ||
| If hosting is blocked, you can work locally and connect the same repository later. |
There was a problem hiding this comment.
@cmcnally, Sorry I was a bit late on this - its already merged. There was just one update that I would make. You could @copilot to do this if you want to.
I feel like the table is to much format, so I would opt for bolded first line CTAs. And also adding some kind of copy-pastable prompt so you can just have an agent do all this stuff would also be beneficial?
Get started with Replica
You don't need to set up everything at once. Start with the guide that matches your next step: trying Replica locally, setting up hosting, or joining your team's existing repository and Hub.
Create your first local prototype. Use a starter template or an existing prototype repository, add team guidance, and build something useful. No Hub required. Quick, easy, low-commitment, just to try it out.
Set up shared hosting and team feedback. Check hosting needs early, build with your team's design guidance, and connect Hub when it is ready.
Join your team's Replica environment. Use its existing setup to create, publish, and review a prototype.
If hosting is blocked, you can work locally and connect the same repository later.
Have Copilot help you get started
Paste the following prompt into the GitHub Copilot app to have Copilot handle this for you:
Please read the GitHub Replica README.md https://github.com/github/replica/. Ask which getting-started path fits my needs, then guide me through it step by step.
There was a problem hiding this comment.
Thanks @arniebradfo! I made both changes in #152: bold link headings instead of the table, plus a copy-paste prompt for Copilot.
## Why After #100 merged, a reviewer suggested that the table in "Get started with Replica" was more formatting than the content needed. They also suggested a copy-paste prompt so new users can have Copilot guide them through setup ([review comment](#100 (comment))). ## What changes - The three getting-started paths are now bold links followed by one short sentence, instead of a two-column table. - A new "Have Copilot help you get started" section gives a prompt to paste into the GitHub Copilot app. Copilot reads the README, asks which path fits, and walks the user through it. The link targets and guide descriptions are unchanged. Co-authored-by: Catharine McNally <2089974+cmcnally@users.noreply.github.com> Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Why
First-time setup crossed between guides and made hosting requirements easy to discover too late. Readers need a clear path for local prototyping, team hosting, or joining an existing setup, without repeating completed work.
What changes
Add a local prototyping walkthrough and make the hosted walkthrough self-contained. State hosting and network requirements early, explain plugin and canvas setup, and give readers precise continuation points for work they have already completed. Keep the repository setup guide explicitly focused on instructions for Copilot.
Update the README and documentation index to explain the three starting paths. Add the AI product framing, product demo, and collapsible music credits while preserving the README's privacy, support, and license sections.
Public playback of the uploaded demo remains unverified: anonymous requests to its attachment URL returned 404.